How to create a documentation site from scratch

Would you like to lead a digital product starting from scratch? This was the question I was asked in my first interview at Empathy.co, and it was precisely the kind of challenge I was looking for.

Later, I discovered that Empathy.co also had the same Asturian blood running through it that runs through mine, and when I learned more about what Empathy Platform could do, it was like an alignment of planets. And so, I jumped straight in.

The challenge

Many challenges arise when building a top-class documentation portal. To begin with, we had to set up a new team, build the product and produce all of its content. Here I’ll share my journey with the public-facing aspects of this new documentation portal, and I hope to write more about the behind-the-scenes aspects in future posts.

Establishing our mission, motto & product goals

Before we jumped straight into developing the product, we had to be clear about our overall goals, how we wanted to impact our customers, and what was most important to us as the EmpathyDocs team.

We defined our general mission:

“To provide our clients, users and partners with the best documentation experience, applying Empathy.co’s core principles of Trust, Understanding and Joy”

We imaged our future with the motto:

“eDocs is the place where Empathy’s values and knowledge converge”

And we defined our 4 product goals:

1. Increase customer satisfaction, trust and commitment.
2. Reduce the workload of the support team by acting as a self-led support tool.
3. Strengthen Empathy.co’s product package by including eDocs portal as a robust support tool.
4. Growing and promoting an Empathy.co developer community.

Start with discovery

To get started, you need a process to follow. We ran the Double Diamond product discovery process to better understand our existing documentation and identify issues and gaps where we could improve.

The popular creative process for ideating or to do Product Discovery, known as the Double Diamond.

Get to know our audience

When building a documentation portal that people will find useful you have to be clear and well researched about who will benefit from it. So, we got down to business asking questions like:

• Who are the intended users of the documentation portal?
• What are their key goals and behaviors?
• What are their real needs?
• What will their journey be?

We identified the different User Personas who used our previous documentation and classified them into two very different types of audience:

• Technical or specialised people such as software developers, who work both at Empathy.co and within the teams of our clients or partners.
• Business people such as merchandisers or retail analysts, and our colleagues from customer success and first line support teams.

We then interviewed people who matched these profiles and learned more about their needs and opinions, what they value and expect from the documentation, and above all, why. Of all the information collected, the most common observations were :

• The documentation was incomplete and incoherently organised, there’s no documentation giving an overview of the entire product.
• There’s no single place to go to with everything that customers / developers using our products would need. Our first line support teams had to repeatedly send links to different sites.
• The negative user experience, particularly from our clients’ developers, resulted in increasing rejection.
• Inadequate maintenance of the technical documentation due to its disconnection from the source code, meant it had to be updated manually and reactively.
• Some of our vital audience were not taken into account in the content creation.

Defining our product

With all this information in hand, we considered what we needed from the documentation in order to meet the needs of our audience whilst, very importantly, aligning with the company’s long-term strategy. We knew that when these elements are misaligned the chance of success is much lower.

We created a list of must-haves:

• Clear and concise content considering all target audiences, with practical examples.
• Clearly differentiated functional and technical documentation.
• Recognisably consistent style that is easy to read and navigate.
• High level of technical personalisation and customisation.
• Documentation is created in a scalable way (Markdown).
• Technical documentation is kept close to source code, docs-as-code philosophy.
• Documentation that scales with the product.
• Automated generation of technical documentation, facilitating its maintenance.
• Collection of feedback and analytics, that always respects Empathy.co’s cookie free policy, improving user experience and trust in the content.

Gathering our tools

With our goals in mind, our first intention was to be practical and not to reinvent the wheel, so we searched the market for a tool that could cover most of our needs. We found some very good ones, but none of them managed to convince us either due to their simplicity or their lack of agility and control in their design. We needed a tool that gave us the flexibility to document more than “just” software.

For my team and I, it seemed strange that nobody had built a tool yet that suited our needs. It would’ve been so much easier to start with an existing tool, but who said this would be easy?

Choosing our tech stack

We spent some time reflecting and defining which technology stack would best meet our requirements. We decided on:

• Markdown to write all documentation content in a scalable way.
• Github to store content and the portal’s source code in different repositories, avoiding unnecessary dependencies.
• Vue.js as the base framework for the website due to its versatility in custom development and because Empathy.co frontend teams use it.
• Vuepress as our pre-rendered static HTML generator based on Markdown files that provide us with tools or functionalities to develop the portal from the start.

Starting our build with MLK and MLP

It was time to get down to business, building a totally new, custom site that takes Empathy.co documentation to another level. It was an ambitious task, but we kept Martin Luther King’s motto with us throughout the process: b

As the Double Diamond creative process indicates, our next steps were to design, develop, deliver, collect feedback, and iterate. And so we did.

We started by building an MLP (Minimum Lovable Product) and quickly realised that we were unable to generate all content at once from the Empathy Platform product so we thought it best to start with just one of the product teams and ask for their collaboration.

The winner was the team at Interface X, the web interface solution for the Empathy.co search experience. They were the perfect team to start with because the user interface is of major interest to both of our target audiences and it would allow us to design functional and technical documentation that was more eye-catching that most.

Working closely with the Subject Matter Experts (SMEs) in the Interface X team, the developers and their product owner, we extracted their knowledge and gathered a minimum of functional and technical content for the MLP.

While all this great content was being created the design, UX and frontend teams built the new portal from scratch starting with these minimum functionalities:

• An eye-catching homepage that’s functional and practical at the same time.
• Intuitive navigation with features like breadcrumbs, table of contents and next links.
• A basic content search engine.
• Interactive code samples.
• Custom components that give technical writers flexibility when generating content.

After a few months of gestation our little baby was born and the eDocs MLP started to crawl. This was the result:

Collecting feedback to iterate

The next step we took was to validate the MLP with different stakeholders. We proposed different scenarios depending on their role and collected very valuable feedback that we analysed in detail.

Some of the lessons learned from the MLP were:

• The interactive map on our homepage wasn’t intuitive enough
• The sidebar navigation required too many clicks to reach the desired information.
• Clarity was required to show where in the portal users were at any time.
• A maximum of 3 levels needed to be implemented to the content architecture to avoid confusion.
• More “digestible” content with better categorisations was needed with articles that could be accessed anywhere.
• A more focused column system was preferred to improve intuitiveness
• The mobile experience needed a total overhaul.

Our 1st iteration goes live

Once we had received our feedback we could create a list of improvements and new functionalities. We could then make a plan to build them or generate the relevant content for the next iteration. We also agreed as a team to collect more feedback from our users once the next iteration was complete in order to continue to improve the portal.

At the beginning of last August we announced the launch of the new documentation portal EmpathyDocs (eDocs), which you can see at docs.empathy.co. Our baby has started to walk.

Go ahead and take a look, we’d really love to hear your feedback.

The future of EmpathyDocs

We are very proud of our progress, but this project will continue to evolve. Building a comprehensive documentation portal for different types of audiences is a challenging and never-ending task. In fact, it is very likely that by the time you read this article we will have already done some more iterations.

In the coming months we’ll be tackling more advanced and complex challenges such as:

• Coordinating all product teams to generate documentation covering the most important gaps in the Empathy Platform documentation.
• Management and synchronisation of the different component versions that are generated by each team at varying speeds and locations.
• Building a private area in the portal for some partners and clients.
• Preparing better documentation for REST APIs.
• Implementing an advanced content search engine.
• … and much more.

I’m looking forward to sharing with you more of the experiences and lessons learned by my team, EmpathyDocs, on this wonderful journey that has really only just begun.

Got any questions? Get in touch!

Special thanks to my entire EmpathyDocs team who is making the portal possible and to my colleagues at Amplify and Design who helped me complete this article. Thanks!